home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
SGI Freeware 1998 June
/
SGI Freeware 1998 June.iso
/
dist
/
fw_ATxgopher.idb
/
usr
/
freeware
/
src
/
xgopher.1.3
/
README.z
/
README
Wrap
Text File
|
1998-01-21
|
17KB
|
439 lines
Installation Notes
on the
Xgopher client
These notes describe Xgopher version 1.3, completed in May 1993.
+---------------------+
| System Requirements |
+---------------------+
Xgopher requires Release 4 or 5 of the X window system, version 11. It uses
the Athena widget set, the X toolkit intrinsics, and the X library.
Xgopher contains many dependencies on the Unix operating system.
PLEASE NOTE: Xgopher was developed using X11R5 platforms. It should work
with X11R4 also, but may require a small change. For most
computers, this change will not be necessary. If you
receive errors when compiling with X11R4, see the note below.
+---------------+
| Documentation |
+---------------+
This README file contains installation instructions.
The Documents subdirectory contains considerable additional information
on porting Xgopher to other Unix systems and configuring Xgopher.
+--------------+
| Installation |
+--------------+
The Xgopher program will likely be obtained as a Unix tar file.
After using tar to extract the contents of this file, perform
the following steps.
1. Modify the configuration file (conf.h). If you do not modify this
file at all, then Xgopher will connect to the University of Illinois
gopher server by default. The comments in the file tell you what
is expected. Possibly little change will be necessary, but at least
consider changing the default top-level gopher server host name to
a server near you. These are just the compiled-in defaults, most
can still be changed at run-time to accommodate individual preferences.
+------------------------------------------------------------------------+
| OPEN WINDOWS ALERT! |
| If you are COMPILING with Sun's OpenWindows (Version 3) libraries, |
| replace step 2 with the steps outlined below for OpenWindows. |
+------------------------------------------------------------------------+
2. xmkmf
(this will turn the Imakefile into a Makefile, if X11R5
is properly installed on your system.)
+------------------------------------------------------------------------+
| If you do not have xmkmf or imake, you can edit and use the file |
| Makefile.NoNo (named to discourage its use), as your Makefile. |
| If you use Makefile.NoNo, skip step 3. |
+------------------------------------------------------------------------+
3. make depend
(this will build the include file dependency information
into the Makefile.)
4. make
(this will compile the 37 or so source files and link them
with X11 to produce the executable file xgopher.)
5. Modify the application defaults file (Xgopher.ad).
Little change may be necessary. However, the entries in this
file (e.g., for host name, port number, help file name, etc.)
override those defaults compiled into xgopher through
the configuration file (step 1).
6. Make the application defaults file (Xgopher.ad) known to X.
There are several ways to do this for testing without installing
the file in a system directory. Choose one of the following -
whichever is most comfortable for you.
IMPORTANT! Although you can test Xgopher with old (pre Xgopher 1.3)
resource files on your system, you may see some warning
messages. These are informatory only. For final installation,
remove all of the application defaults from previous
versions of Xgopher before you install Xgopher 1.3.
a. xrdb -merge Xgopher.ad
b. setenv XENVIRONMENT `pwd`/Xgopher.ad
(`pwd` will return the current directory, which should be the
Xgopher source directory.)
c. if you have your own app-defaults directory, for example, ~/app-defaults:
setenv XAPPLRESDIR ~/app-defaults/
cp Xgopher.ad ~/app-defaults/Xgopher
Note the name change.
COLOR OPTION: If you are using a color display, it is strongly
recommended that you also include the Xgopher
color resources. if you used method (a) above, then
also use:
xrdb -merge Xgopher-color.ad -nocpp
Otherwise, consider using the file Xgopher-complete.ad
instead of Xgopher.ad. The former file has all of the
color resources included in it.
This is sufficient for now, and to let you test. For
permanent installation, see the later section of this
document which discusses color resources.
For final installation, this file will be stored in the X
application defaults directory, with the file named Xgopher.
Depending on where your X (or OpenWindows) libraries are installed,
this will be the file such as /usr/lib/X11/app-defaults/Xgopher.
7. to test:
xgopher
(this executes the xgopher program!)
(If you see messages like this:
Warning: Cannot convert string "indexLabel" to type Widget
It means that you have old Xgopher resources left somewhere in
your resource files or server. The message is probably harmless,
but you should get rid of the old files before installing Xgopher 1.3
permanantly.)
+------------------------------------------------------------------------+
| SUN USER ALERT! |
| Whether you are using X11R5 or Sun's OpenWindows (version 3), |
| you may receive an error saying that Xgopher cannot connect to |
| the gopher server. If this happens to you, see the additional |
| help in the file Documents/Porting. |
+------------------------------------------------------------------------+
8. to install Xgopher on your system:
With root privileges:
make install
make install.man
this should install the 4 files needed by Xgopher.
If you wish to install all of the files manually instead of using the
"make install" sequence, the four files that need to be installed are:
xgopher this is the xgopher 1.3 program. It may be installed
as the file xgopher in /usr/local/bin, for example.
xgopher.help the help text file. It may be installed with this
name in /usr/local/lib, for example. Note that its
path name was compiled in to Xgopher through the Imakefile.
The resource file (Xgopher.ad) can override this.
Xgopher.ad the X application defaults file. It may be installed
as Xgopher, in /usr/lib/X11/app-defaults, for example.
xgopher.man the user documentation (man page). It may be installed
as xgopher.l (letter l), in /usr/man/manl, for example.
+-------------+
| OpenWindows |
+-------------+
Many people compile with MIT's X11 library then use Sun's OpenWindows
server. This is never a problem.
+------------------------------------------------------------------------+
| If you are compiling Xgopher with the MIT X11 software, you should |
| not be using this part of the installation instructions. Return |
| immediately to step 2 above. |
+------------------------------------------------------------------------+
Some problems arise when compiling with the OpenWindows 3 libraries.
OpenWindows 2 cannot be used as it is an implementation of X11R3.
I will try to help people who want to compile with OW3, but I do not
have good access to such a system, nor am I proficient with its use.
With this caveat, I will say that I have invested considerable effort
to understand the problems people have been reporting with OW3 and
in modifying the Imakefile to avoid these problems.
(Solaris 2.1)
My comments here apply to SunOS 4.x, not necessarily to Solaris.
I have had somewhat better luck in my quick visit with Solaris 2.1
using the "standard" procedures - with one exception. For Solaris 2.1,
in the Imakefile, I needed to chande the line
EXTRA_LIBRARIES = -lm
to
EXTRA_LIBRARIES = -lm -lsocket -lnsl
(This line is commented out in the Makefile; you may need to include it
depending on your networking software configuration on your Sun.)
With this change you can probably continue with the installation
procedure as documented above.
You also may need to uncomment out the line beginning "LOCAL_DEFINES"
which defines the symbols SYSV and SVR4 in case your imake templates
do not already define these symbols.
Sun supplies a version of xmkmf and imake. However, these point
to incorrect directories for the build and installation of software.
Also, their Xmu library is broken for dynamic loading.
+------------------------------------------------------------------------+
| There are two solutions to this problem. Choose one of the following: |
| |
| (1) Use the work-arounds I suggest below. |
| (2) Fix everything the right way, patching Sun's software |
| |
| Your desire and ability to modify system files may determine your |
| choice. |
+------------------------------------------------------------------------+
Use either method (1) or method (2) below - not both.
(1) To use the work-around:
I have provided the file Documents/OW3-site.def in the Xgopher
directory, which should correct enough of the problems with Sun's
imake template files to allow you to build Xgopher. Feel free to
modify this file if you need to. You will rename it to site.def
in step 2c below.
To compile with OW3, replace step 2 of the installation instructions
with the following:
2a. Make sure that your environment variable OPENWINHOME is set
to the proper directory - the top level of your OW3 tree.
2b. Edit the Imakefile to uncomment the 3 lines which are
well-marked in the Imakefile:
MKDIRHIER = BourneShell $(BINDIR)/mkdirhier
EXTRA_LIBRARIES = -lresolv -lm
XMULIB = -lm -Bstatic -lXmu -Bdynamic
(Or, Stew Ellis suggests that you can avoid the use of
-Bstatic by using the parameter "-assert nodefinitions".
Use the following line instead of the XMULIB defined above:
XMULIB = -assert nodefinitions -lXmu
I have not tested this.)
2c. Rename or copy the file Documents/OW3-site.def to be site.def.
For example:
cp Documents/OW3-site.def site.def
This file is read by the imake command to build your Makefile.
2d. Instead of xmkmf, use the following command:
imake -DUseInstalled -I. $OPENWINHOME/lib/config
Be sure that this is the imake from $OPENWINHOME/bin/imake
and not an X11 directory. Use "which imake" or check your
path if you are not positive.
The -Bstatic load option (in step 2b) is necessary to avoid loader
warnings of unresolved externals for:
_get_vwShellWidgetClass
_get_applicationShellWidgetClass
I have tried loading without -Bstatic. I get errors telling me that
these are missing, but the resulting xgopher binary still seems to
work. If you are willing to risk a possible future error, you may
omit the -Bstatic option. (Larry Butler butler@rex.cs.tulane.edu
reports that the binarys work fine with either the OpenWindows X
server or MIT's X11R4 server and twm, but that they kill openlook.
I think he is refering to the OpenLook Window Manager.)
(2) To fix everything the right way, patching Sun's software:
* NOTE * I have not tested these patches and cannot take
responsibility for their correct behavior.
They have been kindly supplied by a Sun user
(Dawn Endico).
Apply the following patches to Sun's libXmu and libXt:
libXmu: 100573-03.tar.Z
libXt: 100512-02.tar.Z
They are available from: iskut.ucs.ubc.ca:/pub/ubc/sun-patches
or: dragon.cso.uiuc.edu:/SUN-FIXES
Apply the supplied patch to the OpenWindows xmkmf software.
The file Documents/OW3-xmkmf.patch contains this patch.
You should NOT be using the file Documents/OW3-site.def. That file
is only for working around Sun's xmkmf as a temporary fix.
Then you can use xmkmf as described in step 2 of the installation
instructions for non-OpenWindows systems.
You may still need to load with -lm (the math library). If
you get unresolved external references to routines such as
sin, cos, pow, floor, then insert the line:
EXTRA_LIBRARIES = -lm
near the start of the Imakefile
+---------------+
| X11 Release 4 |
+---------------+
There has been considerable interest in compiling Xgopher under X11R4.
I have tried to provide that capability to the extent possible.
If you use X11R4, certain tests in the file compatR4.h should detect
this and automatically define the symbol XGOPHER_X11R4.
Unlike previous versions of Xgopher, you should not need to take
special action to compile with MIT's X11R4 libraries. However, some
vendor libraries may fail these tests.
If these tests fail, then you should define this symbol
yourself in the file conf.h by removing the comments from the define
statement (or use -DXGOPHER_X11R4 as a compiler option). This will cause
the compiler to omit some minor R5 specific things without loss of
functionality.
I cannot promise to maintain this backwards compatibility forever.
I do not have good access to an X11R4 library for testing so
I must depend on feedback from others to detect release-dependencies.
+---------------+
| Customization |
+---------------+
The installer may wish to customize some of the Xgopher features
such as the image display, telnet, or other commands. These are
all described in the file Documents/Install-Customization. This
document also mentions some alternative "plug-compatible" widgets
that could be used to modify the appearance of Xgopher.
There is another writeup, Documents/Customization, which describes
changes that a user may use in configuring Xgopher. This latter
file should be available to knowledgable end-users.
+------------------------+
| Color Resource Support |
+------------------------+
The supplied defaults file (Xgopher.ad) will work fine on all color
displays and black & white displays. It has no color definitions.
Depending on your users of Xgopher, you may want to install certain
versions of these app-defaults files.
This section is for the installer of Xgopher. A separate document,
"Customization", provides information for other users of Xgopher.
If EVERY Xgopher user has a black and white display screen, then just
use the file Xgopher.ad. (You needn't read further in this section.)
If EVERY Xgopher user has a color display screen, then you can use
the file Xgopher-complete.ad, which has colors defined in addition
to all the rest of the resources. Rename it to be Xgopher.ad and
install it as Xgopher in the system defaults directory.
In many cases, both black and white screens and color screens are
present at an installation. If so, it is poor practice to install
the color resources file only - monochrome users may get poor results
such as black characters on a black background.
One suggestion is to install the standard Xgopher.ad file, then
let each color user keep their own resources file with only color
preferences. This file would be used in their personal .Xdefaults
or xrdb data files. The file Xgopher-color.ad can be copied to
get a suggested set of colors.
For sites running X11R4 and using both color and non-color displays,
the above is the only solution. It will also work with X11R5.
There is another possibility for sites with X11R5. I encourage you to
look at the "customization" option that will allow you to install both
color and B&W resource files, and conditionally load the color one
automatically depending on the screen you are using.
For X11R5, the Imakefile will handle the installation of both the
monochrome and color resources files:
Xgopher-color.ad as Xgopher-color
Xgopher.ad as Xgopher
Then, each and every user can add the following to the file they
input to xrdb:
#ifdef COLOR
*customization: -color
#endif
The #ifdef will determine whether you are on a color screen, and if
so, use the color resource file. The color resource file "includes"
the standard Xgopher resource file.
+----------+
| Problems |
+----------+
Please report and problems, suggestions, or portability problems to
the author of xgopher. e-mail contact is preferred:
Allan Tuchman
Computing and Communications Services Office (CCSO)
University of Illinois at Urbana-Champaign
1304 W. Springfield Ave.
Urbana, Illinois 61801
USA
(217) 244-0048
a-tuchman@uiuc.edu
+--------------------+
| Other Contributors |
+--------------------+
Thanks to all people who took the time to send me their comments,
suggestions, and problems in previous versions of Xgopher.
All bug reports and most of the suggestions have been
incorporated into Xgopher 1.3.
Of course, the present author assumes responsibility for any
problems introduced.